home
download
documentation
mailing lists
wiki
IRC
forums
daily builds
feature requests
bug reports
patches

How To Work With Patches

• Tools Of The Trade
• Newlines
• Problems with Windows Patch
• Creating A Patch
• Submitting A Patch
• Applying A Patch
• Removing A Patch

When we speak of 'patches' in the Rockbox project, we mean a set of changes to one or more source files.

Tools Of The Trade

Use the tools 'diff' and 'patch'. Preferably the GNU versions. They're readily available for all imaginable platforms.

Try one of these:

• http://www.fsf.org/software/patch/patch.html
• http://www.gnu.org/directory/diffutils.html
• http://gnuwin32.sourceforge.net/packages/patch.htm - patch for Windows
• http://gnuwin32.sourceforge.net/packages/diffutils.htm - diff for Windows

Newlines

These tools will assume and operate on "unix-style" newlines. That means all files that you're diffing and patching etc must have LF newlines only, and not the Windows/DOS standard CRLF newlines,

Not complying to this simple fact will cause you grief. Mark my words.

Problems with Windows Patch

For some users, the windows patch program above malfunctioned. If patch doesn't output anything, use cygwin instead (www.cygwin.com). Download setup.exe, and run. Follow instructions as on their site to install. Be sure to include the package "patch" from the utils category. If you use cygwin, you really should be using the cygwin version of diff and patch and not any other.

Creating A Patch

We generate diffs (often called patches) using 'diff' in a manner similar to this:

  diff -u oldfile newfile > patch

People who have checked out code with CVS can do diffs using cvs like this:

  cvs diff -u file > patch

'diff' can also be used on a whole directory etc to generate one file with changes done to multiple:

  diff -u olddir newdir > patch

The -u option means the output is using the 'unified diff' format. Older diff programs don't have that, and then -c (for 'context diff') is OK.

Submitting A Patch

All patches that are meant for inclusion in the sources should follow the format listed on the Contributing to Rockbox page, and be posted to the patch tracker. Patches sent to the mailing list are quickly lost in the traffic of the list itself.

Please keep in mind that not all submitted patches will be accepted. The better you make the patch, the better is the chance that it will get applied soonish.

Applying A Patch

Applying a 'patch' (output from diff -u) is done with the 'patch' tool:

  cd to/source/root
  patch < patchfile

patch knows that the patchfile is a set of changes on one or more files, and will do those to your local files. If your files have changed too much for the patch to work, it will save the sections of the patch that aren't possible to apply in a file called "filename.rej" (filename being the name of the file for which the failing section was intended for). Then you must take care of them manually.

If there is path information in the patchfile that you want to cut off from the left, tell patch how many directory levels to cut off to find the names in your file system:

  patch -p0 < patchfile
  patch -p1 < patchfile
  patch -p2 < patchfile

... each example line removes one extra level of dir info from the left.

You can use the --dry-run option to patch to make sure that the patch applies clean. It doesn't actually apply the patch, only prints what would happen if you run it.

Removing A Patch

You can remove a patch again from the sources by doing the reverse action of a specific patch. You do this with the -R (or --reverse) options, such as:

  patch -p1 -R < patchfile

{ Edit | View raw | Attach | Ref-By | Printable | Diffs | r1.4 | > | r1.3 | > | r1.2 | More }

Revision r1.4 - 17 Aug 2005 - 06:25 GMT - DanielStenberg Parents: DocsIndex	Copyright © 1999-2005 by the contributing authors.